Software Vault: The Diamond Collection/The Diamond Collection (Software Vault)(Digital Impact).ISO/cdr13/nfbtr731.zip/NFBTRANS.FMT

Text File | 1995-01-24 | 67KB | 1,347 lines

~r~f0~p2 Braille Translator User Documentation Release 7.31 January 24, 1995 ~s

~cTABLE of CONTENTS
~f1PART 1: What This Is
~f2PART 2: What You Need to Know and Need to Have
~f3PART 3: How to Use This Program
~f4PART 4: Command Line Options
~f5PART 5: Formatting Commands
~f6PART 6: Braille Considerations
~f7PART 7: Sample Formats
~f8PART 8: Braille Symbols and Contractions
~f9PART 9: Changing the Table
~f10PART 10: External Format Language
~f11PART 11: What to Do When Things Go Wrong
~f12PART 12: Other Considerations

     ~pa ~n1

     ~f1~cPART 1: WHAT THIS IS
     Release 7.30 of the National Federation of the Blind Braille Translation
Program incorporates a number of new features and changes.
     The NFB braille translator is a computer program designed to
easily and quickly produce Grade 2 braille from text entered using a word
processing program. The program has been designed to be as easy to use as we
can make it. Most operators can start producing grade 2 braille with
half-an-hour practice. There are a number of commands that enable you to format
the braille output for almost any purpose.

     Braille, by its very nature, does not have the same format as print text.
A typical braille page consists of twenty-five lines, each of which is forty
characters long. Unlike the standard printed page, most braille documents do
not utilize either a top or bottom printed margin. In other words, on a typical
braille page, all twenty-five lines are used for text. In some cases, the first
line is used for a running header. In braille produced by this program, with
the exception of braille page 1, the upper right corner of the page will
contain a braille page number. See Interpoint printing described later.
Also see the fp= option if you want to number page one.

     Blank lines in braille text are kept to a minimum. In contrast to many
printed formats, braille paragraphs are not separated by a blank line. A
braille paragraph is denoted by an indented line which starts in braille
position three. A blank line in braille might well be used to offset large
portions of quoted text or to precede a centered heading.

     You cannot underline in braille - use italics for emphasis.
     Never use the letter L for the number 1.
     When typing fractions, type 8-1/2 instead of 8 1/2 (There must be a hyphen
between the whole number and fraction)
     By using advanced formatting it is possible to create special format
documents with the NFB braille translator. There are frequently requirements to
produce documents that present information in outline format, for example, a
restaurant menu or a schedule (see SAMPLE FORMATS section of this
documentation.) ~s

     ~f2~cPART 2: WHAT YOU NEED TO KNOW AND NEED TO HAVE
     In general, you will need a computer, an embossor, and word processing
software to use this system. You will need to be familiar with your operating
system and your word processing system. Please be familiar with the various
copying and setup procedures appropriate to your system. Remember to frequently
ask yourself what you would do if you accidentally lost the information on the
diskettes or hard disk you are using. BE SURE YOU HAVE ADEQUATE BACKUPS AT ALL
TIMES.
     Your computer will require at least one floppy disk and at least 256k of
memory. It is best to have two floppy disks or a hard disk. The program itself
uses less than 64k of memory, making it usable on almost any MS-DOS based
system.
     You must also have a brailling device. This can be any embossor or
paperless braille device that uses the Triformation ~aLED-120 coding scheme.
These include the Triformation series, the Thiel, the ~aTED, the Cranmer
Modified Perkins, the Romeo, Juliet, and the Braillo.
     You or your hardware supplier should be sure that the embossor is properly
connected to the computer and is working. The braille translator expects the
embossor to be connected to the default list device. Because the computer could
have more than one print device, the operating system provides ways to change
the default device path. You can redirect the standard list output using the
MODE command, for example, ~0MODE LPT1:=COM1:~2.

     The NFB braille translator does not include a word processor, but is
designed to allow you to use the word processing software of your choice. For
example, you can use WordStar, Word, Perfect Writer, Multimate, or any other
word processing program that can produce a print image disk file. Some word
processing programs, such as WordStar, will permit the braille translator to
work directly on the internal format files. You might try this out with your
word processing software--it will spare you the extra step of creating a print
image file.
     If you are not familiar with the steps required to create a print image
file, consult your word processing user's manual, or someone in your
organization who may know. A print image file, stated simply, is the image of
your file printed to the disk instead of to the paper in your printer.
     If you have problems obtaining a print image file to process, you can
install a disk spooling program if you are using an MS-DOS based system. The
disk spooling program can capture the print output from ANY program and direct
it to a disk file. ~s

     ~f3~cPART 3: HOW TO USE THIS PROGRAM
     1. Set up System embossor hooked up and turned on, proper disks or
programs loaded, operating system displays prompt, etc.

2. Include the location
of nfbtrans in the path in your autoexec.bat file. This allows nfbtrans to be
run from any directory. Nfbtrans looks for the files nfbtrans.cnf and
braille.tab first in the current directory and then in the same directory in
which nfbtrans.exe is located. braille.tab and nfbtrans.cnf are required.

     3. After the prompt, type NFBTRANS, for example:
     (prompt)NFBTRANS Nfbtrans then displays version and copyright messages
depending on the contents of your nfbtrans.cnf file.

     4. The program will then ask a series of questions depending on
nfbtrans.cnf. Many questions can be eliminated by placing options in
nfbtrans.cnf. The following assumes no nfbtrans.cnf: Each question except the
name of the file to be translated will be followed by a standard default
response. To select the default, simply press the RETURN. The questions and
defaults are as follows:
     Please select
     1 to Translate a Text File or 2 to emboss a File that has been Translated.
Choice? 1
     You may either translate a file that you have entered with a word
processing program, or emboss a file that has already been translated. Select
option 1 ONLY if you have already translated and stored a file, and you know
what you named it.

     Source file name?
     Enter in the name of the file you want to translate, such as
B:LETTER.DOC or A:REPORT. Wildcard characters may be used to specify
several files. If multiple files are specified, they are sorted and processed
in alphabetical order. Files beginning with the @ "at" sign are assumed to
contain lists of files to be translated.  You should put only one file name
per line and wildcard characters are allowed in the list.  Blank lines
are ignored.

     Enter number of spaces before left margin of source file (usually 1) 1
     Use another number if the document you want to translate does not fully
left justify. Enter the column of the beginning of the left margin.

     Enter number of braille cells to emboss on a Line (usually 40) 40
     You can specify an alternate line length, such as 42 cells. Just press
return to use default.

     Display Source Text (Y/N): N
     If you do not want to see the source text as it translates or embosses,
enter N.

     Display Translated Text (Y/N): Y
     If you do not want to see the translated text as it translates or
embosses, enter N. Most sighted people like to see it.

     Number of lines per page? 25
     Enter the number of lines per braille page, usually 25. Press return to
use default.

     Number of Line Skips between Pages (99-FF, 999-VT)? 99
     Enter the blank lines between pages to get to the top of the next page. If
you want to use the form feed command (FF), enter 99. The Thiel embossor works
well with the FF command. If you want to use the vertical tab (VT), enter 999.
The old Triformation ~ALED-120 may require the VT depending on the version of
the embossor you have. 0 tells nfbtrans to output blank lines to go to the top
of the next page. Most embossors use the Form Feed--99. Press return to use
default.

     Please select 1 to translate and store in a file or 2 translate and emboss
immediately. Choice? 2
     Select the first option if you want to store a translated file for future
embossing. While the translator is fast, it is even faster to simply emboss a
file that has already been translated. If you only need one copy, select option
2 and emboss the file immediately. See sp= for backround embossing.

     Enter starting page: 1
     Normally, enter a 1 to start at the beginning. If you want to start
further into the document, enter the BRAILLE PAGE NUMBER at which you want to
start.    You may enter the ending page at this time by separating it from the
starting page with a - , or space, for example 1 20.  If ~0ip=1 ~2is in effect,
the starting page must be odd.    If not, nfbtrans subtracts 1.

     Enter last page to emboss:9999
     Normally, enter a 9999 to emboss the entire document. If you want to
emboss fewer pages, enter the BRAILLE PAGE NUMBER at which you want to stop.

     Number of Copies: 1
     Enter the number of copies you want. ~s

~f4~cPART 4: Command Line Options
     The command line options have been enhanced to include the following. You
can specify options either on the command line, in braille.tab, or in
nfbtrans.cnf.
     list of options:

     ~0ca=capital_marks ~2defines how upper case words or letters are brailled.
     Default is ~0ca=,|,, ~2meaning a single uppercase letter is preceeded
     by a dot 6, while multiple uppercase letters by two dot 6's.  Note that
     a vertical bar separates the strings.

      ~0cf=filename ~2 specifies another name for nfbtrans.cnf.

     ~0cl=nn ~2 Specify the maximum length of lines during centering. Maximum value
is page width minus 6. Default is 32.

     ~0co=nn ~2 number of copies example ~0co=3 ~2Use ~0co=0 ~2to always be prompted for
number of copies.

     ~0cs=nn ~2 specifies number of characters your printer can print per second.
It is used to estimate embossing time before file is sent to the DOS
print command. Estimates are given only if 2 minutes or more. Default
is ~0cs=40. ~2

     ~0db=0 ~2 or 1 display braille 0 no 1 yes -1 to be prompted.

     ~0de=delay ~2 specifies delay in MS between lines of embossed output. If
handshaking is working properly use ~0de=0. ~2

     ~0ds=display ~2 source 0 for no 1 for yes -1 to be prompted.

     ~0ef=0/1/2 ~2 default is ~0ef=1 ~2 tells nfbtrans to process the
corresponding ~0.efl ~2 file if it exists.  If the file exists and there is
a syntax error, an error message is displayed and the program aborts.
~0ef=0 ~2 tells nfbtrans not to look for a ~0.efl ~2 file.  ~0ef=2 ~2 tells
the program to abort if the ~0.efl ~2 file is not found.  ~0ef=5 ~2 and
~0ef=6 ~2 are like ~0ef=1 ~2 and ~0ef=2 ~2 except the user is
notified that a ~0.efl ~2 file was processed.
     ~0ex= extension_definition. ~2 You can tell nfbtrans to take certain actions
depending on the extension of the input file. The extensions are followed by
'euqal' and then by a number. For example ~0ex==0c=1h=1pas=1brl=2 ~2 says that files
with no extension use strings from the ~0i0= ~2 option and ~0.c .h and .pas ~2 files are
associated with i1 and brl i2. You can tell nfbtrans to skip files with certain
extensions using '-' as in ~0ex=exe=- ~2 The extensions can be in any order and you
may have several ~0ex= ~2 options in nfbtrans.cnf. The program can store up to 40
extension definitions.    The ~0ex= ~2 option can also be used to specify the basename
of a file.  If a file has no extension, its name is compared to the ~0ex= ~2
options.  For example ~0ex=makefile=1 ~2 associates a file named makefile with
i1.  See nfbtrans.cnf for examples.

     ~0fp=1 ~2 Number first page. Otherwise do not number first page.

     ~0fs=format_string ~2 specifies format characters, usually tilde.
Use ~0fs= ~2 if your document has embedded tilde or carat symbols that are not
nfbtrans format commands.

     ~0gd=n ~2sets the minimum number of guide dots that will be output with
a (tilde)f command. The default is two meaning that if the translated line
has less than two guide dots, they will be converted to blanks.

     ~0gm=0/1/2/3 ~2 Sets graphics mode default is ~0gm=0. ~2Normally nfbtrans
ignores extended graphics characters, characters whose ascii value is
greater than 127.  If ~0gm=1 ~0the high bit is removed. If ~0gm=2 ~2the
     character is left intact. Place the appropriate entries in ~0braille.tab ~2
     if you want to expand these characters.  ~0gm=3 ~2will cause the program
     to abort if a graphics character is used but not defined in the table.

     ~0he=hyphen_extension ~2 file extension, default is ~0he=.hyp. ~2    See ~0rw= ~2option later.

     ~0hk=1 ~2 enables hot keys meaning you don't need to press RETURN when entering
a single digit or answering Y/N.

     ~0i0= ~2 through ~0i9= ~2& ~0ia= ~2through ~0ie= ~2specifies a set of
     three strings that can be associated with a given extension defined with
     the ~0ex= ~2 option. The strings are ~0pre_init, post_init, ~2and
     ~0format_string. Pre_init ~2is processed before the file is embossed
or stored and ~0post_init ~2after. These strings may contain format commands to
invoke grade two, change page length and so forth. Escape sequences can also be
sent. I use this with the Juliet to switch to 8 dot braille for ~0.c .h ~2 and
~0.pas ~2 files. The strings are separated by a vertical bar. The ~0format_string
~2specifies characters considered format characters, usually tilde or carat.
~0.c ~2 files have tilde and carat characters as part of the program text so
~0format_string ~2should be empty. For example ~0i0=pre_init|post_init|format_chars. ~2
See sample nfbtrans.cnf for a real example.

     ~0ip=n ~2 specifies interpoint mode printing on both sides of the page. Even
page numbers are not printed. Printer advances to beginning of next odd page
after file is printed. Use ~0ip=2 ~2 to tell printer to advance an entire blank
page so you can reach a perferation below the bottom page. Note that if ~0sp=1 ~2
is in effect the embossor only advances to the next page rather than skipping an
entire blank page. Otherwise there would be a blank page between each file.

     ~0it=char ~2specifies the character used for italics, the default is
     underscore which translates to dots 46 in ~0braille.tab. ~2

     ~0kc=0/1 ~2 if 1 do not convert control characters to spaces.

     ~0l0=string.  ~2This option removes the space after any character in
"string."  For example ~0l0=,; ~2removes spaces after words ending in
a comma or semicolon. If there isn't enough room for the joined word,
the second word is placed on the next line. This option is used in
some of the foreign language tables.

     ~0l1=- ~2 joins a word containing a single dash to the preceeding word.
This option is normally used only in certain foreign language tables.

     ~0le=file ~2loads an external format language file.

     ~0lf=loadfile ~2 Use the ~0lf=loadfile ~2 option to emboss a large document
consisting of several files. The ~0lf= ~2 option cannot be used on the command
line or in nfbtrans.cnf. The ~0lf= ~2 option can only be invoked with a format
command so formatting must not be disabled. For example if you have your
document broken in to files ~0ch1.fmt ~2and ~0ch2.fmt, ~2place ~0tilde-lf=ch2.fmt ~2 as the
last word of ~0ch1.fmt. ~2 This causes nfbtrans to continue translation by reading
~0ch2.fmt. ~2 Page numbering and so forth continues as if only one file were being
translated.

     ~0li=string ~2will append "string" to the last word of each input line.
The string is appended after translation.

     ~0lm=left_margin ~2 use ~0lm=0 ~2 to be prompted for left margin.

     ~0ls=n ~2 lines to skip between pages. use ~0ls=-1 to ~2always be prompted for
this. ~0ls=0 ~2 is allowed now. I like printing 27 lines per page. My Juliet
automatically advances over the paper fold after the 27TH line. No formfeeds
are output if ~0ls=0. ~2 Use ~0ls=99 ~2 for formfeeds.

     ~0mm=2 ~2 Maximum main menu choice. Set to 3 to display the back
translation choice which isn't complete yet.

     ~0nc=1 ~2 skip copyright message.

     ~0ow=1 ~2 If an output file is created, you will not be warned if the file
already exists.

     ~0pa=n ~2 where n is an integer. Use this option if your brailler and
synthesizer are connected to the same port. ~0pa=10 ~2 causes the program to pause
and beep once a second for 10 seconds giving you time to switch between your
synthesizer and brailler. This only happens when you emboss, not when you just
write to disk. Nothing will be written through the bios to the screen while
you are embossing. Pressing any key during the pause will cause the program to
wait until another key is pressed before continuing with the pause sequence. If
escape was pressed the program aborts and returns to DOS. When embossing is
complete the program beeps and waits for a keypress before continuing. This
prevents the DOS prompt or other program output from being brailled. The
~0pa= ~2 and ~0sp= ~2 options cannot both be used.  The last one given is used.

     ~0pd=1/2 ~2 and ~0pf=1 ~2 causes date and filename to be printed on the first
line of the first page of your document. ~0file.txt 05/30/93 14:56 ~2
is the format.
Use ~0pf=2 ~2 to print just the file name rather than the whole path.  For example
with ~0pf=2 nfbtrans c:\dir1/dir2/myfile.txt ~2 will be embossed as
~0myfile.txt ~2 on the first line of output. Use ~0pd=2 ~2 to print the
date without the time.

     ~0pe=ending_page ~2 -1 to always be prompted.

     ~0pl=nn ~2 page length default ~0pl=25 ~2

     ~0pn=prn ~2 print device for your brailler if ~0sp=0. ~2  By default, ~0pn=prn. ~2

     ~0ps=page_start ps=-1 ~2 to be prompted.

     ~0pw=page_width ~2 default ~0pw=40. ~2

     ~0qm=0/1 ~2 sets quiet mode.  If ~0qm=1, ~2 page number progress messages are
not output.

     ~0rw=number ~2 rejoins words default is 1.  By default nfbtrans attempts to
rejoin hyphenated words if the following is true.  1. The last word
on a line ends in a dash and the preceeding character is a letter and
the word does not contain other dashes and the word does not contain math
symbols.  2.  The following word starts with at least
two letters.  ~0rw=0 ~2 tells nfbtrans not to rejoin words.  ~0rw=1 ~2 greatly
improves braille output. Nfbtrans will consider characters above decimal
127 to be letters if you add eight to the ~0rw= ~2option.  For example ~0rw=10
~2 outputs proposed hyphenated words to standard error and considers
characters above 127 as letters as well as a-z and A-Z.
~0rw=2 ~2 outputs the words that were joined to standard error during
translation. This is used for debugging purposes.
You can choose which words are joined by doing the following:
1.  Set ~0rw=5 or rw=6. ~2  Run nfbtrans and output the file to disk or nul.
This makes a first pass through your document storing proposed hyphenated
words in a hyphen file.  The hyphen file has the same name as the input
file with a ~0.hyp ~2 extension.  For example if you are embossing ~0c:\text\file.txt ~2
the hyphen file would be ~0file.hyp ~2 in the current directory. Use the ~0he= ~2
option to change the hyphen file extension.
2.  After the first pass, edit this file and change any lines with words you
don't want joined.  Any change to a line tells nfbtrans not to rejoin the word.
3.  Emboss your file as you would normally do with nfbtrans.  The hyphen
file will be read and compared with the proposed hyphenated words.  Those
lines that have been modified will cause nfbtrans not to rejoin that word.
~0rw=6 ~2 also outputs the words to ~astderr like ~0rw=2. ~2  The hyphen files are
deleted after the second pass.

     ~0s0=pre-init ~2 string sent to printer if in spool mode. Use to tell printer
to ignore formfeeds. the dos print command appends a ff at the end of each
file.

     ~0si=file ~2 specifies the file name nfbtrans uses if input is redirected.
     For example if you have ~0si=stdin.c ~2 in nfbtrans.cnf and issue the
command nfbtrans ~0<myfile, ~2 the file myfile will be treated as if it were a
~0.c ~2 file because nfbtrans will see the name ~0stdin.c. ~2  Default is ~0si=stdin. ~2

     ~0sp=0/1/2 ~2 sets spool mode. Output to be embossed is sent to a temporary
file and then that file is printed with the dos print command. If your
printer supports it, tell it to ignore formfeeds with ~0s0=. ~2  Your
printer will continue ignoring formfeeds until it is powered down or reset
because nfbtrans has no way of resetting it. It is important that the
print command is resident before nfbtrans is run. Otherwise memory may not be
released properly.  The temporary file is usually placed on your ram disk.
Use the environment variable TMP or TEMP to tell nfbtrans where to put it,
otherwise it goes in your current directory. You must have sufficient memory
to execute the print command while nfbtrans is running. Otherwise nfbtrans
reports the error and exits. These temporary files aren't deleted when printing
is complete so its best if they are on a ram drive. The files are created
from the hour, minute and second 183742 for example.
There is a limit, approximately 9, on the number of files in the print queue.
So if you run ~0nftrans *.* ~2 all the files will be stored as the
temporary files but only the first 9 may be printed.  Use the syntax
nfbtrans ~0*.*;n ~2 to start embossing at the nth file.
Use ~0sp=2 ~2 to pause for the estimated embossing time.  Press any key to
translate the next file immediately.  In theory this should prevent
program from overflowing the print queue. ~0pa= ~2 and ~0sp= ~2 cannot be
used at the same time.    The last one specified will be the one used.

     ~0tm=translation_mode. ~2 ~0tm=1 ~2 chooses 1 for the first choice requesting a
number. ~0tm=21 ~2 chooses 1 for the first and 2 for the second input.

     ~0so=0 or 1 ~2 turns sound off or on. Turn sound off if you are annoyed
by the beeps and clicks. Pressing <SPACE> during translation toggles sound
on or off.

     ~0st=filename ~2 specifies the name of a file containing statistics about the
file you just translated. Example:
~s~0wed 03/30/94 11:54
Input File: VE.TXT
Translation time: 2 minutes 26 seconds
LinesPerPage: 27
LineLength: 43
Words: 48776
Pages: 220
Words per Page: 221
Words per Second: 334
Estimated Embossing Time: 106 Minutes
Total Cells: 224323
Total Dots: 503196
Dot1: 104372 = 20%
Dot2:  90510 = 17%
Dot3:  86612 = 17%
Dot4:  89838 = 17%
Dot5:  74979 = 14%
Dot6:  56885 = 11%
Input file length: 288231
Output file length: 236227
Output is 81% of input
Entries in table: 864 ~2~s

If the statistics file already exists, the new output is appended to the file.

~0td=table_definition ~2 defines the format for a table with multiple columns.
The table definition string follows the same format as the ~0sprintf ~2
function familiar to C programmers. The table definition string is made
from one or more field specifiers. A field specifier begins with a percent
sign, the field width, and a lowercase ~ls.  There may be spaces or other
characters between field specifiers. A negative field width as in ~0%-8s ~2
defines a field of eight characters that is left justified. A positive field
width is right justified. If the table definition contains spaces use double
or single quotes.

The table definition is aplied to each input line and the columnized line
is output. You must use some common sense in the table definition. The sum
of all the field widths plus any characters must be less than or equal to the
page width. You can have up to eight fields defined in a table definition.
It is important that  output fields not be larger than the corresponding
field definition.  If you are translating to grade II the length of the output
field could be larger for example when the dollar sign is expanded. Lines
with page numbers can contain a table entry if there is room, otherwise the
table will continue on the next line.

If a column translates to an accent mark, the column is output as spaces.
If the table is in Grade II, precede the accent with a vertical bar. One use
for this would be if you want to right justify a five column field on a line
width of 40 characters.  The table definition would be
(tilde)~0-td="%15s%15s%10s" ~2 so if you want to right justify hello you
would immediately follow the table definition line with two vertical bar,
accent pairs and then hello.

Example: Define a table of four columns all right justified with column 1
being 5 characters, columns 2 3 and 4 8 characters.
The table definition would be (tilde)~0-td=%5s%8s%8s%8s ~2 Since 5 plus 8
plus 8 plus 8 equals 29, the width of the table output is 29 characters.
Each input line is translated and then output according to the field
specifiers in the table definition.  Suppose the input line is 23 5.7 6.2 7.8.
This line has four fields; the first will be output according to the first
field specifier which is ~0%5s ~2 which means right justified in a field of
five characters.

End the table output with a (tilde)~0-td="" ~2two double quotes which removes
the table definition. This option is not allowed on the command line or
in nfbtrans.cmf.

     ~0tf=table_file ~2 immediately loads the given table file
containing translation rules.  This can be used to load different rules for
different languages. This new table remains in effect until another table
is loaded. If you plan to translate more than one file using wildcards, the
original ~0braille.tab ~2 file should be reloaded at the end of the file.
For example you could set up nfbtrans.cnf to load russian.tab every time
a .rus file was translated. To do this, add ~0rus=9 ~2 to an ~0ex= ~2 option
assuming ~0i9 ~2 is not in use. Then add the line
~0i9=(tilde)-tf=russian.tab|(tilde)-tf=braille.tab| ~2
You could also reload a default table in nfbtrans.cnf.    The table file is
assumed to be in the same directory as nfbtrans.cnf.

     ~0tv=number ~2 sets timing value. Only used with nfbasm and Microsoft C. On
faster machines the delay may not be long enough. Turbo C automatically takes
your machine's clock speed into account. ~s

     ~f5~cPART 5: Formatting COMMANDS
     The braille translator recognizes several commands that will change its
actions. The computer differentiates a command from some other character string
because the command starts with a special symbol, either the tilde (tilde) or
the carat (carat). You may use whichever symbol is easiest for you on your
computer; each has the same effect. The command itself is not translated into
braille, but instead only modifies the action in the program. Formatting may be
disabled for a given extension using the ~0i0 -i9= ~2option. Many times I want to
print a document with tilde or carat symbols embedded in it which are not
nfbtrans formatting commands. Nfbtrans will terminate if an unknown format
command is encountered. Disabling format commands also disables special
treatment of ||.
     For example, you can switch from grade 2 braille output to grade 1 braille
output within a document by using the (tilde)1 to indicate grade 1 and then the
(tilde)2 to indicate grade 2. The translator will go from grade 2
(the default) to grade 1 and then back to grade 2. Note that the case of
the command doesn't matter (tilde)A is equivilent to (tilde)a.
     Here is a list of the commands and a brief description of their actions:

     (tilde)A PUT THIS WORD ONLY IN GRADE ONE: (Acronym for National Education
Association will look like this: ~ANEA; otherwise, it would look like N, or N
comma.) Read Braille Symbols and Contractions section of documentation to
determine whether there might be a conflict when brailling acronyms.

(tilde)B TEXTBOOK PAGE BREAK IN INKPRINT DOCUMENT: Follow the (tilde)B
immediately with a number to indicate the textbook page. The Braille translator
will flush any translation in progress, insert a line of dots 3 6, and
terminate the line with the text page number indicated. The indicated print
page number prefixed by a letter to indicate the relative Braille page will be
embossed at the top of each Braille page. The actual Braille page number will be
embossed in the lower right-hand corner of the page.

     (tilde)C CENTERING LINES: Put centering command in front of word.
     Centering is in effect until a new paragraph is encountered. This could be
a blank line or one beginning with blanks.
Nfbtrans automatically breaks
lines up in to the proper length for centering. You can specify this using
the ~0cl= ~2 option.

     (tilde)D DOUBLE SPACES BRAILLE DOCUMENT: PUT ON A LINE BY ITSELF. This
command will cause a blank line to appear after each full Braille line.
Use (tilde)~lD to terminate
this feature.

     (tilde)E POETRY FORMAT: The poetry command can be helpful in
translating poems. This can be considered the opposite of text format (tilde)t
as far as the generated Braille output is concerned. Indented lines of text in
the print image file will cause the Braille output to be written flush against
the left margin with subsequent Braille lines indented two spaces--in other
words, a Braille hanging paragraph. Lines not indented in the print image file
will cause the Braille output to be indented two spaces from the left margin.
Terminate poetry formatting by using (tilde)t.

(tilde)F TABLE OF CONTENTS LINE: (Dot 5
fill): This command has two modes of operation.

If (tilde)f is not immediately followed by a digit:
 Set up your table of contents page at the head of the document using
zeroes for page numbers, and the (tilde)F. For example:
(tilde)FWHAT IS THE NATIONAL FEDERATION OF THE BLIND 00
The (tilde)F will cause the text to be left justified, the
page numbers to be right justified, and dot 5 fill between them. Braille out
the document noting the page numbers of the actual sections. Reedit the
document, replacing the zeroes with the actual page numbers. Finally, Braille
out the finished version. The translator will handle multiple lines if you
continue the table of contents line in cell one of the following line. For
example:
(tilde)FAll Publications and Brochures Distributed by the National
Federation of the Blind, Job Opportunities for the Blind, and the American
Brotherhood for the Blind 00
By default, Table of Contents lines are broken at the pagewidth minus six
column. This may be changed by placing a colon immediately after the ~lf
and then the number.  For example (tilde)~0f:12 ~2 Chapter Five
will cause TOC lines to be broken at column 31 width pagewidth of 43.

Starting with Release 7.27, you can tell nfbtrans the last word of a table
of contents line.  Doing this prevents lines with only guide dots and the
last word from being output. Words starting with a dollar sign or accent
at the end of an input line are considered to be the last table
of contents word.  If the word starts with an accent, the accent character
is removed.  If you are making a table with items and prices using the
(tilde)f command, lines will always be output with both item and price on
a single braille line since the last word on the input line contains a
dollar sign as the first character.

If (tilde)f is followed by digits:
You can tell nfbtrans to automatically put the
correct braille page in your Table of Contents.  You can use this new method
for creating a Table of Contents and still use the old method for other
types of tables.  Carefully follow these steps:

     1.  Place a (tilde)f0 at the beginning of your document.  If you want to
use the ~0pf= or pd= ~2 options, the (tilde)f0 must come first.  (tilde)f0
tells nfbtrans that two passes are required and that your document will be embossed
or written to disk on the second pass.    If the (tilde)f0 is not first, nfbtrans
may output lines before it determines a second pass is required.  This
would certainly mess up the format of your document when the second pass
begins.

2.  Set up the Table of Contents entries with the (tilde)f followed by a number.
Later on in your document use the (tilde)f followed by that same number to indicate
that that first entry corresponds to this title.  Do not put a page number
as the last word on the first Table of Contents line, nfbtrans will do that.
Here is an example to illistrate:
(tilde)f1Chapter 1 Getting Started
(tilde)f2Introduction
(tilde)f3Installation
(tilde)f4Chapter 2
(tilde)f5 chapter 3

Then any time later in your document you could have
(tilde)f1(tilde)cChapter 1
Then later on after any number of pages you could have
(tilde)f5(tilde)cChapter 3

The program reports an error if there is a (tilde)f1 with no previous (tilde)f0.
You currently can have up to 200 toc entry/title pairs.
If you have a (tilde)f75 entry, you must have a matching (tilde)f75 title entry.
The program verifies this after pass 1 is complete.  Also you cannot have more
than two entries with the same number.    The entries can be in any order
as long as there are exactly two entries with the same number.
     The program assumes the first occurrence of (tilde)f14
for example is a TOC entry and the second (tilde)f14 is on the page corresponding
to that entry. This should greatly simplify creating a braille Table of
Contents. Note that if you emboss a range of pages for example page 5 to 16,
the program does a complete pass one to do error checking and then outputs
the desired pages on pass two.

     (tilde)G SET RIGHT MARGIN: PUT ON LINE BY ITSELF. Follow
this command with a number.

     (tilde)H HEADERS: Use this command to cause a
header at the top of each Braille page. Terminate the headers with a (tilde)J or
change the header with another (tilde)H.

     (tilde)I ITALIC SIGN: In Braille, italics replace
underlining. If there are three words or less underlined, put an italics sign
in front of each word. If there are four or more words, put two italics before
the first word and one italic before the last word. Use ~0(tilde)i ~2followed
by a backslash to turn on italics mode. The program outputs two italics
before the current word. Anoter ~0(tilde)i ~2backslash turns off italics mode
and outputs a single italics mark.

     (tilde)J TERMINATE HEADER: Turns off the header feature.

     (tilde)K TERMINATE FOOTER: Turns off footer feature.

     (tilde)L LETTER SIGN: In Braille, letters that stand alone are often
preceded by a letter sign, (dots 5-6). The (tilde)l command is used to
generate this symbol. For example, a capital B standing alone represents
the word, ~abut; C, ~acan, and so on, emphasizing the need for a letter
sign. Put the letter sign before or in a word, Apartment 3-~lC.

     (tilde)M CHANGE MARGIN: PUT ON LINE BY ITSELF. Follow
this immediately with a number indicating the column in which the
Braille left margin should begin--normally, column one. It is best to put the
margin command on a line by itself. The next line will be indented to the
declared new margin. For example, to change left margin, do (tilde)M03 and to
change back, do (tilde)M01 (line return). You see margin changes commonly in
print to se toff large chunks of quoted material. In Braille, however, handle
such a chunk of information with the same print margins as the rest of the text.
But separate the chunk from the rest of the text by placing a blank line (tilde)s
before the material and a (tilde)s blank line after the material.

     (tilde)N SET PAGE NUMBER: You may set or reset the page number by including
a (tilde)N followed immediately by the page number of the next page.
(tilde)NNN PUT ON LINE BY ITSELF.

     (tilde)O INDENTS HANGING PARAGRAPH: PUT ON LINE BY ITSELF. If
there are reasons that you would prefer to have a hanging paragraph indented
more than two spaces, use this command followed by a number such as
5.

     (tilde)P Page command.   This command has several
modes. If you place (tilde)p as the only characters in the word the command
will cause the Braille embossor to skip to
the top of the next page.  If followed by a letter, (tilde)pa for example, the
program skips to the top of the next odd numbered page if you are using
interpoint mode.  Use this to begin embossing at the top of the next right
facing page.

If followed by a number for example (tilde)p4, the program skips to the next
page if there is a blank line within 4 lines from the bottom of the page. This
can be used to prevent centered titles and so forth from being printed on
the bottom of a page. The command is normally given in the beginning of the
document and remains in effect until another (tilde)p number command is
issued.

If followed by a colon and a number for example ~0(tilde)p:5 ~2 causes a
page break if the output is within four lines of the bottom of the page.
This could be used if you have a paragraph you didn't want split on two pages.
Note that the (tilde)p colon command does a (tilde)p0 and then restores the
original value at the beginning of the next page.

     (tilde)Q CLEAR ALL TABS: This clears all tabs inserted in the formatted
document by using the (tilde)V.

     (tilde)R MAKE ROMAN NUMERALS: This command makes Roman numerals on each
Braille page. Use (tilde)N to switch to Arabic.

     (tilde)S INSERT A BLANK LINE: PUT ON
LINE BY ITSELF. This command inserts a blank line in the Braille output.
Otherwise, the translator will eliminate all blank lines. The program will now
treat a blank line like a paragraph indent even if the following line is left
justified.

     (tilde)T TEXT FORMAT: PUT ON LINE BY ITSELF. The text format is the
default format--that is, the format that the translator uses unless it is told
to do otherwise. When the translator normally formats text, it forces all
indentation to the third cell, wraps all overflow to the first cell of the next
line, and appends following left-justified lines. The program will now treat a
blank line like a paragraph indent even if the following line is left
justified.

     (tilde)U TURN OFF ALL PAGE NUMBERING: Use this command to disable all page
numbering.

     (tilde)V SET TAB: A (tilde)V followed by a column number will set a tab
to this location. Now you may use the (tilde)X to skip to this column.

     (tilde)W FOOTER LINE: The footer command will cause a line to emboss at the
ottom of every page.

     (tilde)X TAB: This command causes a skip to the next tab. If no tabs have
been specified, the output will skip to a space. If the command is followed
by a number, the output will skip the number of spaces specified.

     (tilde)Y LIST FORMAT:
PUT ON LINE BY ITSELF. This feature keeps information at the left margin with
runovers of any line followed in the print text by a line return being indented
two spaces (cell 3). If list items exceed one print line in length, the first
word of the second line must be preceded by five spaces in order to be
formatted properly.

     (tilde)Z TERMINATION COMMAND: The termination command inserts a
termination sign (dot 6 followed by dot 3) into the text wherever it is placed.
The termination sign in Braille is used to indicate the emphasis in a word that
is only partly underlined or italicized. For example, if you wanted to
emphasize the ~1dis ~2in dismount: ~idis ~zmount.

(tilde) underscore: causes a hard carriage return beginning a new braille line.

     (tilde)0 DISABLE ALL TRANSLATION:
This command causes the program to do no translation at all. The output will be
what is sometimes called "Computer Braille." The output file will have the same
case as the input file. Please note that letters ~lA through ~lZ will be lower
case, that is, without capital marks. (tilde)01 produces a modified grade 0
output. I have experimented with 8-dot braille and found it takes some getting
used to. (tilde)01 is grade 0 with braille capital marks. It is more compact
than 8 dot braille. This does not conform to any braille code I know of but is
an alternative to 8 dot braille. It can be used to braille ~0.c, .cpp or .h~2
files. It also is useful for brailling unix man pages where the case of the
options is very important. note that an error is reported if you put two
grade commands on a word.  This is because all format commands are processed
before the word is translated.    For example if you had (tilde)0this(tilde)2
the (tilde)2 would be in effect for the whole word.

     (tilde)1 TRANSLATE TO GRADE ONE BRAILLE: This command causes grade 1
Braille output.

     (tilde)2 TRANSLATE TO GRADE TWO BRAILLE: This command causes grade two
output.

     (tilde)3 TRANSLATE TO GRADE THREE BRAILLE: This command causes grade three
output.
You can translate to Grade Three in stages.  Use (tilde)31 to use dot 4, 5, 45 and 456
letter contractions.  Use (tilde)32 to use dots 4, 5, 45 and 456 number
contractions.  Use (tilde)34 to include dot 4, 5, 45 and 456 contractions with
characters other than number or letter characters. If you want letter and
number contractions, add the values for letters and numbers 1+2  = 3 =
(tilde)33.

     (tilde)4 BLOCK MODE.

     (tilde)5 BLOCK PARAGRAPH, blank line of input causes new
braille paragraph.

(tilde)6 Automatic formatting.    The program examines up to the first 1000 lines
of a file before translation.  If the number of blank lines is greater than
the number of lines starting with four spaces then block paragraphs are assumed.

     (tilde) left square bracket ~0[ ~2 sends ESC or ~0chr$(27) ~2 to the printer.
Any text after the bracket will also be sent up to the next tilde
character in the word.

     (tilde)~0-xx=string ~2 where
~0xx=string ~2 is a valid command line or ~0nfbtrans.cnf ~2 option. For example
(tilde)~0-pl=25 ~2 sets page length to 25.

     (tilde)' FORCED APOSTROPHE: The forced apostrophe eliminates
ambiguity where the single quote mark is used. For example, if you had to force
an apostrophe in vernacular, "~'ave a ~'eart, me love."

     (tilde) right square bracket ~0']' ~2 Force leading and trailing outer
quotes at any time.

     (tilde) right curly brace ~0'}' ~2 Force inner quotes at any time.

     You can insert any character without translation by preceding it with the
(bar symbol) character. For example, |,| b|en will prevent the BE sign from
appearing since that is not correct Braille usage.

     TO INTERRUPT NFBTRANS AT A PROMPT: Control SCROLL LOCK or BREAK key on
your keyboard will exit NFBtrans and take you to the ~lC prompt. Pressing <ESC>
during output causes program to abort. ~s

             ~f6~cPART 6: Braille Considerations
     Type the word "times" in mathematical formats.
Type the word "equal" or "equals." Type the word "divide" for the division
sign. Type the word "percent" when the percent sign stands alone. Never use the
number sign. Type the word "dollar."
     The translation program ignores empty lines -- use the (tilde)S to skip
a line in the braille output.
     A simple way to check that the embossor is working properly is to turn it
on, start up the computer, and, while you are still at the operating system
level enter a CONTROL-P at the keyboard.
     This will cause anything you type or the computer displays to be echoed to
the default list device. Since your default list device should be the brailler,
the characters you type should be echoed to the braille embossor. If they are,
then everything should be ready for the translator to work. Type a CONTROL-P
to turn off this echo feature. This technique allows you to determine that the
path from the operating system to the embossor is working properly. ~s

~f7~cPART 7: Sample Formats

     Following are some sample formats to help you get an idea of
the differences between braille format and print format.  If you
look these over you will see how easy it is to edit print text to
make it braille out in the proper format.

CHART

(tilde)~CTitle of chart           (centered)
(tilde)~S                  (skip a line)
(tilde)~Y                  (left justify)
Expenses:

(tilde)~M3                 (indent to cell 3)
Business

(tilde)~M5                 (indent to cell 5)
1984: $1234.56
1985: $3222.23

(tilde)~M3                 (back to cell 3)
Personal

(tilde)~M5                 (indent to cell 5)
1984: $341.12
1985: $678.90

(and so on....) ~m1

     FORCED APOSTROPHE

(tilde)(apostrophe)--FORCED APOSTROPHE:  The forced
apostrophe eliminates ambiguity where the single quote mark is
used.  For example, if you had to force an apostrophe in
vernacular:

     She said, "He always dropped his aitches when he said,
'(tilde)(apostrophe)Ave a ~'eart, me love.'"   (Note the forced
apostrophe before ~'ave~'.)

SIMPLE LETTER

(tilde)~Y           (to left justify header lines)
Date
Addressee
Address
City, State Zip
(tilde)~S           (skip a line)
Dear So and So:
(tilde)~T           (normal text format)

  Paragraph text. ------ ----------- ----------- ------- --------
---- ------ ---------- ------ ------------ ---------- ------- ------
-------- ------- - ----------- --------- - - ----------- -- ----------
------- --------- ------ ---------- ----------.
  Paragraph text. ------- ----------- -------- ------ -----------
------- --------- ------------ ------------- ------------- -------
----- --------- -------- ------- -------------.

(tilde)~S           (skip a line)
(tilde)~Y           (to left justify trailer)
Sincerely,
Name
Title
(tilde)~S           (skip line)
enclosures

LIST FORMAT

     In some cases, as in the brailling of poems or agendas, it
is desirable to set up a "hanging paragraph" arrangement in
braille--that is, where the first line of a paragraph begins at
the left margin and all subsequent lines of the paragraph are
indented two spaces. Refer to the poetry format (tilde)E for
further information about how to accomplish this.

     Individual elements in the list are often separated by
semicolons, as below.
     Example:

~T
    Following is a list of items for sale, quantities on hand,
and the cost of each:
~Y
Finest brass banjo picks; 100; $1.50
Flannel lined puppy baskets; 12; 13.50
Genuine surplus space program sky hooks; 17; $324.00
Slightly used soft leather turkey booties; 43; $2.25
~t

POETRY FORMAT

~e
     I have a little shadow that goes in and out with me,
     and what can be the use of him is more than I can see.
     He is very, very like me from the heels up to the head;
     and I see him jump before me, when I jump into my bed.
~t (if returning to text)

OUTLINE FORMAT

~CTitle of Document           (centered)
~S                   (skip a line)
~Y                   (left justify)
I. Heading

~M03                   (indent to cell 3)
~LA. Subheading            (note letter sign)

~M05                   (indent to cell 5)
1. Information text ----------- -------------- ------ ------------
   -------- -------------- ------------------- --------- ----------
   ----- ----- ------------.         (note that if information block
                    continues it is INDENTED)
2. Information text ----------- -------- --- - --------- -----------
   ----------- ---------------- -------------- ------------- ------
   -- --------- -----------.

~M03                   (back to cell 3)
~LB. Subheading            (note letter sign)

~M5                  (indent to cell 5)
1. Information text --------- ------- ------------ ---------------
   ----- ----------- ---------------- ----------- ----------- ------
   -- -------------- ------.
2. Information text -------------- ---------- --------- ----------
   ----- ----------- ------.

(and so on....) ~m1

SUBHEADINGS AND TEXT MIXED

~CTitle of the Document        (centered)
~S                   (skip a line)
~Y                   (left justify subhead)

Subtitle
~T                   (normal text)

  Paragraph text. ---------- ----- ------- ------------- -----------
----- --------- ------------------ ----------------- --------- ------
------ -------- ----------- -------- --------- ------ ------ ----------
----- ------ ------------- -------.
  Paragraph text. ------- ---------- ------------ ----- ------------
---- --------- ------------ --------- ---------------- --------------
----- ------ -------- ----- -------.

~S                   (skip line)
~Y                   (left justify subhead)
Subtitle
~T                   (normal text)

  Paragraph text. ---------- --- - - -- ----- ------ --------- ---------
------- ---- -------------- ------.
  Paragraph text. ---------- ------ ----------- --------- -------- -----
--------- --------- ------ ------------ - -----
-- ------- ------ --------- -------- ------ ----------- --------- ------
-- -------- ----------- ----------.
~t
     There are frequently requirements to produce documents that
present information in outline format, for example, a restaurant
menu or a schedule.

     Such a document could be setup as follows:

~CSample Schedule of Events      (Center Title)
~CFirst Annual Potato Festival
~S                  (Skip a Line)

     The First Annual Great Potato Festival will be held in
beautiful Spud Auditorium on the campus of Tuber University.  The
fee for the event will be $25.00 which includes the Tuesday night
banquet and dance.  The dance will feature the crowning of the
Potato Queen and her court, as well as live music by Rocky and
the Mashers.

~S
~Y                  (Change to List Format)
Tuesday Events
~M3                 (Indent to cell three)
10:30 - 12:30  Introductions and Registration
1:00 - 2:00 Luncheon
2:30 - 3:30 Potatoes and the International Balance of Trade
4:00 - 5:00 Ten new ways to use Potato Skins in the Home
7:00 - ? Banquet and Dance
~T ~m1                     (Reset to Text)
~S
   Seminars will be held in the Peeler Room.  The banquet will
take place in the Grand Potato Ballroom.  Refreshments and drinks
can be purchased in Mr. Chips' lounge.

TABLE OF CONTENTS

~FIntroduction to Bagpipes 00
~FRecorded History of Bagpipes in Europe 00
~FTypes of Bagpipes found in the British Isles 00
~FBagpipes in War and Politics 00
~FBagpipe Music Today 00

     The (tilde)F will cause the text to be left justified, the
page number to be right justified, and dot 5 fill between them.
Braille out the document noting the page numbers of the actual
sections.  Reedit the document, replacing the zeroes with the
actual page numbers.  Finally, braille out the finished version.
The translator will handle multiple lines if you continue the
table of contents line in cell one of the following line.  For
example:

     ~FA Long and somewhat tedious description of the impact of
Bagpipe music on indoor plants 00

(See automatic page numbering for Table of Contents described earlier)

UNDERLINING
     Italics and underlining in braille are indicated by an
italic sign, as there is no other way to create an underline or
special slanted character.  The (tilde)I can be used to
generate the italic or underline indicator.  Indicate that a word
is underlined or italicized by preceding it with the (tilde)I
command.  If there are more than three words in a row to be
italicized, precede the first word with TWO italic commands.  For
example, suppose you had text as follows:

     The American people will (start italics) not (end italics) tolerate
the concept of (start italics) rule by a vocal but small minority.(end
italics)

     You may produce the desired effect in braille by entering
the following:

     The American people will ~Inot tolerate the concept of
~I~Irule by a vocal but small~I minority. ~s

        ~f8~cPART 8: BRAILLE SYMBOLS AND CONTRACTIONS

     The complete table of contractions is available for
modification. Treat it carefully!  Always keep a backup!

     These are some of the contraction and punctuation symbols
used by the braille translator.  Note -- the capital sign looks
like a comma.

AND   &
FOR   =
WITH  )
(percent)     3P
AR    >
GG    7
(zero)       J
(semicolon)    2
BB    2
GH    <
(one)      A
(comma)     1
BE    2
HIS   8
(two)      B
(exclamation)      6
BLE   #
ING   +
(three)     C
(question)     8
BY    0
IN    9
(four)       D
(colon)     3
CC    3
OF    (
(five)       E
(slash)     /
CH    *
OU    \
(six)      F
(ellipses)   '''
COM   -
OW    [
(seven)      G
(period)     4
CON   3
SH    %
8     H
(dash)      --
DD    4
ST    /
(nine)       I
(hyphen)     -
DIS   4
THE   !
(left paren)     7
(start quote)      8
EA    1
TH    ?
(right paren)      7
(end quote)    0
ED    $
TO    6
(left brace)     ,8
(apostrophe)     '
EN    5
WAS   0
(right brace)      8'
(plus sign)    +
ER    }
WERE  7
(ampersand)    @&
(reverse slash)     ;
FF    6
WH    :
(asterisk)     99
(dollarsign)     4
~s

~f9~cPART 9: CHANGING THE TABLE

     The table of braille contractions exists in braille.tab. It is read when
you start nfbtrans.  It gets read again only when necessary for example
when going from Grade Two to Three or Grade Three to Two or when a new table
file is specified with the ~0tf= ~2option.

A portion of the table appears below:
1(bar)AFTERNOON(bar)AFN
1(bar)AFTERWARD(bar)AFW
1(bar)AFTER(bar)AF
2(bar)AGAINST(bar)AG/
2(bar)AGAIN(bar)AG
1(bar)AGREEA(bar)AGREEA

     Each table entry consists of three parts separated by the vertical bar.
The table exists in normal ascii format of text followed by cr-lf. The first
part of an entry is a type indicator, the second part is the match string, and
the third part is the replacement string.  Type 28 is slightly different.
It is used to match control or graphics characters.  To expand tab for example
use ~028|09|<tab> ~2  9 is the ascii value of tab.
Match strings consisting of two or more digits are taken to be the decimal
equivilent of the character.  Match strings defined like this have a length
of 1.  The actual graphics character may also be entered.  Characters above
decimal 127 must have type 28 or 29.
The simplest types are as follows:
1-replace anytime, 2-replace only if whole word match, and 3-replace if whole
word or at beginning of word.  See the comments in braille.tab for a complete
list of types.
     The table is stored in alphabetic order with the more specific string
ahead of the more general string. Study the table carefully before you change
it. Be sure you have a backup. Improper braille.tab entries will produce
incorrect braille. If errors are found, the program reports the type of error,
the line number of the error, and then aborts. Entries are converted to upper
case but must be in the proper order.
     Grade 3 is only partially implemented. Type entries > 32 are for grade 3
and entries less than 0 indicate the entry is not to be used if in Grade 3. ~s

     ~f10~cPART 10: EXTERNAL FORMAT LANGUAGE

     The NFB Braille Translation Program includes an external format
language. The external format file is created with a word processor. This file
is used by the translation program to format the file in addition or instead of
imbedded tilde commands. NOTE-ALL THE TILDE COMMANDS WORK AS THEY ALWAYS HAVE.
The external format language was developed to ease the brailling of standard
columnar computer reports, but it can be used for many other standard formatting
tasks. External Format Language files must have a .efl extension.  If the option
~0ef=1 ~2 is specified the program searches for the .efl file with the same name
as the file you are translating.  If you are translating myfile.txt, myfile.efl
is processed if it exists.  ~0ef=2 ~2 tells nfbtrans to abort if myfile.efl is
not found.  Add four to the number if you want nfbtrans to output the name
of the .efl file and the message saying processing is complete.
The external format language tells the translator how to process a given input
file. The file may or may not have imbedded tilde commands.

The external format
file is made up of command sets. Each command set starts with the word LINE
followed by one or two numbers. The first number refers to the starting, or
only, line, and the second number if present refers to the ending line for this
command set. The commands in the command set following the LINE command are in
effect only for the lines specified. As each line is read from the input file,
the program checks each LINE command to determine if it applies to the line
read. Of course, the beginning and ending line can be such that all the lines
in the text input file can be affected. For example,
     LINE 1 9999
     would cause the program to apply this command set to lines 1 through 9999.
     The LINE command can be followed by subcommands that affect braille
translation as follows:
     LIST -- change formatting to list format with hanging indent.
     TEXT -- change to normal text formatting.
     CENTER -- center the line when it is brailled.
     DELETE -- delete this line entirely.
     SKIP -- skip a line.
     INDENT -- indent unmatched lines.
     PAGE # -- set page length of input text.
     MATCH # # 'ccccc' -- search for match with columns.
     FIELD # # -- define a field.
     OMIT -- delete defined field.
     STATE -- expand two character state codes.
     APPEND 'ccccc' -- append character(s) to field.
     The last three commands, OMIT, STATE, and APPEND always follow a FIELD
command.
     For instance, to center line two, you might enter a command line in the
external format language file as follows:
     LINE 2 CENTER
     You may stack multiple commands. For instance, you could enter
     LINE 3 LIST DELETE SKIP
     which will change the format at line three to list from whatever it may
have been, delete the line from the braille output, and insert a blank line.

     The PAGE command has no counterpart in the imbedded commands. It is used
to specify the page length of the source document. If the PAGE is specified as
zero, the input text file will be treated as a single page no matter how long
it is. The default page size is 66. The page line counter will be reset every
66 lines or at the top of page character, whichever comes first.

The MATCH command is also unique to the external format language. This command makes all
the commands that follow it in the command set dependent on a matching
condition. The program scans the lines specified in the LINE command within the
columns specified on the MATCH command for the character string following the
column specifiers. You may use spaces if the character string is enclosed in
quotes. The two numbers immediately following the MATCH command specify the
beginning and ending columns. If there is no match, the program will proceed to
the next LINE command. If there is a match, the program will apply the
following commands in the command set.
     The INDENT command is also unique to the external format language. It
tells the translation program to indent any lines which are not MATCHED, and
for which a FIELD command is active. This facilitates the creation of subtotal
groups in financial reports. An example is provided.
     The FIELD command must be followed by two numbers defining the starting
and ending columns of a field. This field can be deleted by adding the OMIT
subcommand. If the field is a two character state code, you can cause the
translator to expand it to the full state name by using the STATE subcommand.
Finally, you can append data to the field by using the APPEND subcommand. Most
often, you will append a delimiter such as a semi-colon or a comma to a field.
However, you can also use the append command to add any text, even including
spaces if you use quotes.
     For example, let us assume a columnar report showing states ranked by
number of bagpipe-playing tugboat captains. There are three columns: rank,
state code, and count. We can format the columnar part of the report with a
command set as follows:
     LINE 10 60 FIELD 20 21 STATE APPEND ; FIELD 1 19 APPEND ;
     We assume the columns occur from lines 10 through 60, as specified
following the LINE command. We ignore the count field since we do not need to
append a delimiter--the count field is at the end of the line. We tell the
program to select the field starting at column 20 and ending at column 21,
translate it to a full state name from a state code, and append a semi-colon.
Then, we tell the program to select a field from column 1 through column 19 and
append a semi-colon. These field commands are applied from lines 10 through 60.
NOTE THAT WE START WITH THE RIGHTMOST FIELD. The reason for this is that the
program processes the commands in order. The field command changes the location
of the columns to the right. Hence, the column alignment is lost. By starting
with the rightmost field first, columns to the left are still properly aligned.
ALWAYS START WITH THE RIGHTMOST FIELD. The program verifies that the fields
are in the proper order and that they don't overlap. The program aborts if
it finds an error.

Release 7.26 adds three REPLACE commands to the EFL. These commands are
followed by two strings; the first is the search and the second is the replace
string which may be empty. The search strings are case insensitive.

1. repl search replace.  This command searches the specified lines.  If the
line contains the search string, the entire line is replaced with the
replacement string.  The line will be deleted if the replacement string is
empty. For example the .EFL line line 1 9999 repl "copyright 1994" "" would
delete all input lines containing the string "copyright 1994".  Note that quotes
are used because the string to be replaced contains a space.

2. reps search replacement replaces the search string with the
replacement string. The string is replaced without regard to word boundaries.
For example the command line 1 9999 reps "is not" isn't replaces every
occurrence of "is not" with isn't.

3. repw search replace.  This searches a line for the search string. The
entire word containing the search string is deleted and the replace string
is substituted. For example in the RFB DOS 6.0 manual headings are
indicated by heading1, heading2 ... with tildes before the ~lh and after the
number.  These titles could be centered with the command
line 1 9999 (tilde)heading (tilde)c.  Each heading specifier will be replaced
by (tilde)c wich is the nfbtrans centering format command.

     The External Format Language feature is quite powerful, and can save you a
great deal of editing effort, particularly for columnar reports or frequently
produced reports in specific formats. For most documents, you will probably
find it just as easy to continue to use the imbedded commands. For computer
reports, and financial reports, you should consider setting up a EFL command
file to save yourself time and effort.
The external formatting language is a bit tricky, but it has considerable power. ~s


     ~f11~cPART 11: WHAT TO DO WHEN THINGS GO WRONG

     STOP STOP STOP STOP STOP STOP
     That is what to do first. STOP. Take your fingers off the keyboard and
take a break while you consider the situation. Most computer related problems
start out with a simple problem that could be easily fixed. Often, we rush to
fix the problem without thinking. Unfortunately, this often makes a simple
problem MUCH, MUCH WORSE.
     1. STOP. Sit back and consider the situation. 2. Determine your fallback
situation. Do you have backups? 3. Can you make a backup of your current
situation? If you can, it might be a good idea to do so. Quite often word
processing programs will make automatic backups. You can preserve these by
copying your entire work disk, and then renaming the backup. 4. Can you tell if
it is a hardware or software problem? You may want to run another program such
as your word processor to determine whether the computer is generally working.
If the embossor isn't working, you might want to try the CONTROL-P test to
echo the keyboard input directly to the embossor. (See How to Use This Program
section of this documentation.) 5. Write down the problem in your log book. If
you don't have a problem log start one. You, or someone you work with, may have
the same problem again, and it is handy to have something written to refer to.
6. Don't forget to write down the resolution of the problem for future
reference. 7. Check your documentation. There may be a note that will help you
easily fix the trouble. IT PAYS TO BE FAMILIAR WITH THE DOCUMENTATION. 8. Call
for help. If it is obviously hardware, call the hardware support. For software
problems relating to the operating system or word processor, call the
appropriate support. ~s

~f12~cPART 12: Other considerations

Translate your files from scratch for brailling rather than embossing an
already existing file.    Nfbtrans outputs over 1500 characters per second in
Grade II mode on a 20MHZ 386 machine so translation time shouldn't be a
problem. One possible problem is that this version may format documents
slightly differently than earlier versions.  This means that page 25 may
be different between this and earlier versions for example.
     When embossing an existing file with lineskips = 0, make sure the correct
lines per page value is in effect. If it isn't, there is no way the program can
tell what page you are printing.
     The external format language has not been completely tested. If there is a
problem, send the .efl and the text file with the problem.
     Please use my internet address [e-mail] to send files if possible.